Narrative of a Rendering

For reference

For advanced work it is useful to know the narrative of the process whereby a page is built; this averts mistakes, and orients you when exploring or debugging. As a beginner you don't need to know what's going on behind the scenes, but when you become an advanced Frontier webmaster you may find this useful. You can skip this page now if you want -- it will still be here when you want to come back to it.

General Questions

Where are the scripts?

If you edit the menubar at system.menus.menubar, take a look at the scripts attached to the Web menu. (Highlight a menu item and click the Zoom button.) Most of those scripts call html.something.

Where are the html scripts?

They're at system.verbs.builtins.html. It's a big table: there are many scripts.

What's the difference between previewing a page and publishing a page?

Selecting Preview Page or Publish Page sends a page through the same process. The difference is where the page is written to to disk.

Publish Page

Suppose you select a page and choose Preview Page or Publish Page.

The menu script calls html.commands.previewPage or html.commands.releaseRenderedPage.

All that html.commands.previewPage does is set a flag saying that this is a preview. It then calls html.commands.releaseRenderedPage.

html.commands.releaseRenderedPage

This script finds out which page we want to build. It calls html.buildObject which builds the page. When it returns, it calls html.ftpText which writes the page to disk. Finally it shows you the page in your browser.

html.buildObject

This script is where most of the work is done. It starts by getting the page data table ready. It empties it out or creates a new one as necessary.

Then it calls html.buildPageTable, which reads directives and prefs and creates the entries in the page data table.

Then, if your site has a #filters table containing a firstFilter script, that script is called.

Then the script locks the page data table with a semaphore before calling html.tenderRender, which runs the directives embedded in the page.

Next this script ensures that the location on disk of this page has been set up properly, based on #ftpSite and any directives in the page itself.

Then if your site has a #filters.pageFilter script, that gets called.

Now comes the fun part: the page gets built.

First the page's template is read into a local variable. Any directives in the template are processed.

Then the content of the page is placed in the same local variable, replacing the {bodytext} tag.

Macros and glossary look-ups are then processed via a call to html.processMacros. This is where your macro scripts are evaluated and items in double-quotes are replaced with glossary entries. (Or left alone when there is no matching glossary entry.)

Then html.buildObject fixes up relative (glossPatch) links, so that links to pages within your site are always relative. It calls another macro -- html.data.standardMacros.glossaryPatcher -- to do this job. (In 5.1, this macro is now implemented in C, but the old script code is still there if you want to see what's happening.)

If the page has a #pageHeader attribute (as opposed to a {pageHeader...} macro call), then this is built next.

If you're rendering on a PC, you probably have #addLineFeeds set to true. This simply converts line feeds from cr to cr/lf feeds.

If this is a fat web page, then the fat information is next added at the end of the page, after the closing html tag.

Before html.buildObject returns, we run the script at #filters.finalFilter if there is one.

Back to html.commands.releaseRenderedPage

As stated above, this script next writes the page to disk by calling html.ftpText. Finally, it shows you the page in your browser.

That's it, in a nutshell. You can go through these scripts yourself if you like.

If you've learned how to use Frontier's debugger, create a script with one line:

   html.commands.releaseRenderedPage \
      (@websites.samples.randomStuff)

Step into that script and see where it leads you. Be prepared to spend some time at this: a fair amount of code is being executed every time you build a page. But the quick narrative above should provide a good background.